home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / CIncludes / DebuggerSupport.h < prev    next >
C/C++ Source or Header  |  1996-05-01  |  14KB  |  310 lines
  1. /*
  2.      File:        DebuggerSupport.h
  3.  
  4.      Contains:    Public interface to kernel services for debuggers
  5.  
  6.      Version:    Technology:    System 8
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __DEBUGGERSUPPORT__
  19. #define __DEBUGGERSUPPORT__
  20.  
  21. #ifndef __TYPES__
  22. #include <Types.h>
  23. #endif
  24. #ifndef __KERNEL__
  25. #include <Kernel.h>
  26. #endif
  27. #ifndef __MACHINEEXCEPTIONS__
  28. #include <MachineExceptions.h>
  29. #endif
  30.  
  31. #ifdef __cplusplus
  32. extern "C" {
  33. #endif
  34.  
  35. #if PRAGMA_IMPORT_SUPPORTED
  36. #pragma import on
  37. #endif
  38.  
  39. #if PRAGMA_ALIGN_SUPPORTED
  40. #pragma options align=power
  41. /* the following contents can only be used by compilers that support PowerPC struct alignment */
  42.  
  43. #if FOR_SYSTEM8_PREEMPTIVE
  44. /*
  45.  In addition to the normal kernel API, the kernel provides a set of services
  46.  which are specific to debuggers.  These services are all accessed through the
  47.  DebuggerSupport library.
  48.  This first service is debugger registration and unregistration.  For a debugger
  49.  to register itself with the kernel, it calls DSRegisterDebugger.  (The kernel
  50.  allows only one registered debugger; multiple debuggers can be supported
  51.  externally by registering a dispatching entity as the debugger.)  When a debugger
  52.  has successfully registered itself, it is able to receive exceptions from
  53.  debuggable tasks.  Unregistering is simply the reverse of registering.  The
  54.  kernel automatically unregisters a debugger when it terminates if the debugger
  55.  has not already unregistered itself.  DSRegisterDebugger should be the first
  56.  call made to this library.
  57.  To receive an exception, the debugger calls DSWaitForException, passing it a
  58.  pointer to a DSExceptionRecord and a time limit.  This call blocks until either
  59.  an exception arrives or the time limit expires (pass kDurationForever to wait
  60.  indefinitely).  Note that this semantic essentially requires the debugger to
  61.  be multithreaded.
  62.  A DSExceptionRecord contains the ID of the excepted task, along with the IDs
  63.  of the task's team and address space, and a message ID corresponding to the
  64.  particular exception.  The details of the exception are contained in the
  65.  exception record's ExceptionInformation structure, which includes pointers
  66.  to the task's registers and other exception state.  The debugger may directly
  67.  modify this exception data, and, within limits, these changes will be forced
  68.  into the task's state upon resuming execution.  (Changes to certain parts of
  69.  the exception data, such as the privileged and interrupt enable bits of the
  70.  exception MSR, will be ignored.)
  71.  DSResumeFromException is used to resume the excepted task's execution or to
  72.  propagate the exception on.  It takes as parameters the exception ID and an
  73.  exception return status.  The status may be either noErr or any nonzero error
  74.  code.  noErr signifies that the debugger has cured the exception and the excepted
  75.  task should continue execution, using the state from the exception data.  Any
  76.  other status value will cause the exception to be propagated to the installed
  77.  exception handler, if any.  If there is no installed handler, or if that handler
  78.  fails to cure the exception, the exception is again presented to the debugger in
  79.  another message.  This time, returning a nonzero return status will cause the
  80.  task to be terminated.  (Double notification of exceptions allows a debugger to
  81.  catch exceptions either first, last, or at both times.)
  82.  Not all exceptions will be sent to the debugger.  Exceptions in kernel tasks
  83.  or in kernel code which runs on behalf of user tasks is not debuggable through
  84.  normal means.  Furthermore, exceptions occurring in privileged tasks with
  85.  hardware interrupts disabled, or during execution at secondary interrupt level,
  86.  or while running message system Accept functions, fall into the same category
  87.  as kernel exceptions and are not sent to the debugger.
  88.  The debugger may call DSHoldTasks to request the kernel to hold a task or set
  89.  of tasks, making them ineligible for execution.  The tasks are specified with a
  90.  task ID and scope (task only, task and children, task family, or task team).  If
  91.  any task to be held is already blocked inside the kernel, e.g. due to a page
  92.  fault, I/O operation, or message send, holding it will cause it to remain
  93.  ineligible even after it has unblocked.  Releasing held tasks with DSReleaseTasks
  94.  allows them to become eligible again.
  95.  DSGetTaskState is used to determine a task's scheduler state (runnable or blocked),
  96.  and, if blocked, what its PC and SP values were at the point it blocked.  If a
  97.  task is running a software interrupt it will have scheduler state for both its
  98.  normal execution and the execution of the software interrupt.
  99.  DSReadMemory and DSWriteMemory are used to access task memory.  To read memory,
  100.  the debugger simply calls DSReadMemory.  To modify memory, the debugger must first
  101.  call DSCreateMemoryAccess to obtain a memory write access right to the desired page
  102.  of memory.  Using that access right, it may then call DSWriteMemory to perform the
  103.  modification.  DSWriteMemory performs appropriate processor cache synchronization and
  104.  backing storage coordination to support modifying code memory, e.g. for instruction
  105.  breakpoints.  DSDeleteMemoryAccess is used to release an access right.
  106.  Some implementations of the kernel and hardware may support data breakpoints.  To
  107.  find out what data breakpoint support (if any) is available, the debugger calls
  108.  DSGetDataBreakpointInformation.  DSSetDataBreakpoint is used to set or clear a
  109.  data breakpoint.  The implementation may cause excess exceptions which will have to
  110.  be filtered out by the debugger:  breakpoints may occur in the wrong address space
  111.  or on an address which is outside the range specified but which lies within the
  112.  resolution range supported by the implementation.
  113.  Exception notification record
  114. */
  115. struct DSExceptionRecord {
  116.     TaskID                             exceptedTaskID;
  117.     KernelProcessID                 exceptedKernelProcessID;
  118.     AddressSpaceID                     exceptedTaskAddrSpaceID;
  119.     MessageID                         exceptionID;
  120.     ExceptionInformation             exception;
  121. };
  122. typedef struct DSExceptionRecord DSExceptionRecord;
  123.  
  124. typedef DSExceptionRecord *DSExceptionRecordPtr;
  125. /* Task state record*/
  126. struct DSKernelState {
  127.     SchedulerState                     kernelState;
  128.     LogicalAddress                     PC;
  129.     LogicalAddress                     SP;
  130. };
  131. typedef struct DSKernelState DSKernelState;
  132.  
  133. typedef DSKernelState *DSKernelStatePtr;
  134. struct DSTaskState {
  135.     DSKernelState                     taskState;
  136.     DSKernelState                     swiState;
  137. };
  138. typedef struct DSTaskState DSTaskState;
  139.  
  140. typedef DSTaskState *DSTaskStatePtr;
  141. /* ID to specify write access rights to a particular page in logical memory*/
  142. typedef struct OpaqueDSMemoryAccessID* DSMemoryAccessID;
  143. /* SchedulerState values*/
  144.  
  145. enum {
  146.     kInactiveState                = '    ',
  147.     kPageFaultState                = 'PFLT',
  148.     kMessageSendState            = 'MSND',
  149.     kMessageReceiveState        = 'MRCV',
  150.     kHeldState                    = 'HELD',
  151.     kEventFlagState                = 'EFLG',
  152.     kTerminatingOtherProcessState = 'OTRM',
  153.     kTerminatingCurrentProcessState = 'CTRM',
  154.     kTimerDelayState            = 'DLYQ',
  155.     kKernelQueueState            = 'QBLK',
  156.     kRunState                    = 'RUN ',
  157.     kSemaphoreReadState            = 'MSRD',
  158.     kSemaphoreWriteState        = 'MSWR',
  159.     kTaskStartingState            = 'STRT',
  160.     kTaskTerminatingState        = 'TERM'
  161. };
  162.  
  163. /*
  164.  Describes the data breakpoint facility provided by the current implementation.
  165.  maxBreakpoints is the maximum number of data breakpoints available (may be zero).
  166.  breakpointResolution determines the worst case range of addresses to which a data
  167.  breakpoint applies, as follows:  if the nominal breakpoint address is addr, the
  168.  actual range of addresses breakpointed may, in the worst case, be
  169.     [(addr & ~(breakpointResolution - 1)) ..
  170.             (addr & ~(breakpointResolution - 1)) + breakpointResolution - 1].
  171. */
  172. struct DSDataBreakpointInformation {
  173.     ItemCount                         maxBreakpoints;
  174.     ByteCount                         breakpointResolution;
  175. };
  176. typedef struct DSDataBreakpointInformation DSDataBreakpointInformation;
  177.  
  178. typedef DSDataBreakpointInformation *DSDataBreakpointInformationPtr;
  179.  
  180. enum {
  181.     kDataBreakpointInformationVersion = 1
  182. };
  183.  
  184. /*
  185.  The access types to which a data breakpoint should apply.  Use
  186.  kDSBreakDisable to clear a data breakpoint.  Note that the implementation
  187.  may not support breakpointing read and write accesses independently; in
  188.  that case specifying either option will have the same effect (break on
  189.  any access).
  190. */
  191. typedef OptionBits DSDataBreakpointOptions;
  192.  
  193. enum {
  194.     kDSBreakDisable                = 0x00000000,
  195.     kDSBreakOnReadAccess        = 0x00000001,
  196.     kDSBreakOnWriteAccess        = 0x00000002
  197. };
  198.  
  199. /*
  200.  Debugger Services functions
  201.  Register the debugger.  Returns kernelIDErr if there is already a debugger
  202.  registered.
  203. */
  204. extern OSStatus DSRegisterDebugger(void );
  205.  
  206. /*
  207.  Unregister the debugger.  This is also done automatically by the kernel if
  208.  the debugger terminates.
  209. */
  210. extern OSStatus DSUnregisterDebugger(void );
  211.  
  212. /* Wait specified amount of time for an exception message from the kernel.*/
  213. extern OSStatus DSWaitForException(DSExceptionRecord *exceptionRecord, Duration timeLimit);
  214.  
  215. /*
  216.  Resume execution of a task halted by an earlier exception.  If exceptionReturnStatus
  217.  is noErr, resume the task, else propagate the exception.  If the propagated exception
  218.  remains unhandled, a second exception notification will be generated.
  219. */
  220. extern OSStatus DSResumeFromException(MessageID exceptionID, OSStatus exceptionReturnStatus);
  221.  
  222. /* Make the specified task(s) ineligible for execution, until released by DSReleaseTasks.*/
  223. extern OSStatus DSHoldTasks(TaskID taskID, TaskRelationship scope);
  224.  
  225. /* Make the specified held task(s) eligible again for execution.*/
  226. extern OSStatus DSReleaseTasks(TaskID taskID, TaskRelationship scope);
  227.  
  228. /*
  229.  Get the scheduler state for a task.   The task may be in a software interrupt or in
  230.  normal execution; if normal, state->swiState.kernelState will be kInactiveState.  In
  231.  either case, the appropriate state->taskState.kernelState or state->swiState.kernelState
  232.  will be kRunState if the task is running, and if so the corresponding PC and SP values
  233.  are invalid and will be returned as zero.  If the task is blocked in normal execution
  234.  then state->taskState.PC and state->taskState.SP will reflect the PC and SP at the time
  235.  of the system call which caused the task to block.  Similarly, if the task is blocked
  236.  in a software interrupt, hence not running, then state->swiState.PC and state->swiState.SP
  237.  will be nonzero.
  238. */
  239. extern OSStatus DSGetTaskState(TaskID taskID, DSTaskState *state);
  240.  
  241. /*
  242.  Create a write access right to the page for logical address dstAddr in address
  243.  space addrSpaceID.  This makes the page physically resident and prevents subsequent
  244.  reads or writes of the page from or to backing storage.  The access right is returned
  245.  in memAccessID.
  246. */
  247. extern OSStatus DSCreateMemoryAccess(AddressSpaceID addrSpaceID, LogicalAddress dstAddr, DSMemoryAccessID *memAccessID);
  248.  
  249. /*
  250.  Modify the memory to which an access right has been obtained.  memAccessID is the access
  251.  right, dstAddr is the target address, srcDataPtr points to the source data to be written,
  252.  and numBytes is the size of the write.  The range [dstAddr..dstAddr + numBytes - 1] must lie
  253.  entirely within the page specified by the access right.  If the destination memory is code,
  254.  processor caches will be synchronized appropriately.
  255. */
  256. extern OSStatus DSWriteMemory(DSMemoryAccessID memAccessID, LogicalAddress dstAddr, void *srcDataPtr, ByteCount numBytes);
  257.  
  258. /*
  259.  Delete an access right and allow normal backing storage activity for that page.  memAccessID
  260.  is the access right.  Note: changes to the page up to this point will NOT be written to
  261.  backing storage.
  262. */
  263. extern OSStatus DSDeleteMemoryAccess(DSMemoryAccessID memAccessID);
  264.  
  265. /*
  266.  Read memory.  srcAddr is the address to read from, addrSpaceID specifies the address space,
  267.  dstDataPtr points to the debugger buffer into which to copy the data, and numBytes is the
  268.  size of the read.
  269. */
  270. extern OSStatus DSReadMemory(AddressSpaceID addrSpaceID, LogicalAddress srcAddr, void *dstDataPtr, ByteCount numBytes);
  271.  
  272. /*
  273.  Set a data breakpoint.  addrSpaceID specifies the address space, which may or may not be
  274.  used.  breakAddr is the logical address to break on.  numBytes is a hint as to the range
  275.  of addresses to break on.  The address range [breakAddr .. (breakAddr + numBytes -1)] must
  276.  lie within the worst case data breakpoint resolution which the implmentation supports, as
  277.  determined via DSGetDataBreakpointInformation.  A data breakpoint hit will result in a
  278.  memory access exception of type kDataBreakpointException.  The implementation may cause
  279.  excess exceptions which will have to be filtered out by the debugger, e.g. breakpoints
  280.  may occur in the wrong address space or on an address which is outside the range specified
  281.  but which lies within the resolution range supported by the implementation.  To "fix up"
  282.  a memory reference which triggered a data breakpoint exception without removing the
  283.  data breakpoint, use DSReadMemory or DSWriteMemory.  Data breakpoints may be disallowed
  284.  on certain addresses which are used by system code; DSSetDataBreakpoint will return
  285.  kernelInUseErr for such addresses.
  286. */
  287. extern OSStatus DSSetDataBreakpoint(AddressSpaceID addrSpaceID, LogicalAddress breakAddr, ByteCount numBytes, DSDataBreakpointOptions options);
  288.  
  289. /*
  290.  Get information about data breakpoint support.  Returns the number of breakpoints available in
  291.  the current implementation and the worst case address resolution of a data breakpoint.
  292. */
  293. extern OSStatus DSGetDataBreakpointInformation(PBVersion version, DSDataBreakpointInformation *info);
  294.  
  295. #endif
  296.  
  297. #pragma options align=reset
  298. #endif /* PRAGMA_ALIGN_SUPPORTED */
  299.  
  300. #if PRAGMA_IMPORT_SUPPORTED
  301. #pragma import off
  302. #endif
  303.  
  304. #ifdef __cplusplus
  305. }
  306. #endif
  307.  
  308. #endif /* __DEBUGGERSUPPORT__ */
  309.  
  310.